home *** CD-ROM | disk | FTP | other *** search
/ PC World Interactive 7 / PC World Interactive 7.iso / program / dosref.EXE / CHAPTER.009 < prev    next >
Text File  |  1996-01-31  |  51KB  |  968 lines
  1.  
  2.        **  Programmer's Technical Reference for MSDOS and the IBM PC **
  3.  
  4.                             C H A P T E R   N I N E
  5.  
  6.  
  7.                           INSTALLABLE DEVICE DRIVERS
  8.  
  9.  
  10.                                 C O N T E N T S
  11.  
  12. Device Driver Format .................................................... 9**
  13. Types of Devices ........................................................ 9**
  14.         Character Devices ............................................... 9**
  15.         Block Devices ................................................... 9**
  16. Device Header ........................................................... 9**
  17.         Pointer to Next Device Header Field ............................. 9**
  18.         Attribute Field ................................................. 9**
  19.                 Bits 0 and 1 ............................................ 9**
  20.                 Bit 2 ................................................... 9**
  21.                 Bit 3 ................................................... 9**
  22.                 Bit 13 .................................................. 9**
  23.                 Bit 14 .................................................. 9**
  24.                 Bit 15 .................................................. 9**
  25.         Pointer to Strategy and Interrupt Routines ...................... 9**
  26.         Name/Unit Field ................................................. 9**
  27. Creating a Device Driver ................................................ 9**
  28. Installing Device Drivers ............................................... 9**
  29.         Installing Character Devices .................................... 9**
  30.         Installing Block Devices ........................................ 9**
  31. Request Header .......................................................... 9**
  32.         Unit Code Field ................................................. 9**
  33.         Command Code Field .............................................. 9**
  34.         Status Field .................................................... 9**
  35. Device Driver Functions ................................................. 9**
  36.         INIT ............................................................ 9**
  37.         MEDIA CHECK ..................................................... 9**
  38.         Media Descriptor Byte ........................................... 9**
  39.         BUILD BPB (BIOS Parameter Block) ................................ 9**
  40.         INPUT OR OUTPUT ................................................. 9**
  41.         NONDESTRUCTIVE INPUT NO WAIT .................................... 9**
  42.         STATUS .......................................................... 9**
  43.         FLUSH ........................................................... 9**
  44.         OPEN or CLOSE (DOS 3.0+) ........................................ 9**
  45.         REMOVEABLE MEDIA (DOS 3.0+) ..................................... 9**
  46. The CLOCK$ Device ....................................................... 9**
  47.  
  48.  
  49.  
  50.  
  51. DEVICE DRIVER FORMAT├──────────────────────────────────────────────────────────
  52.  
  53.  A device driver is a handler for communication between the system software
  54. and hardware devices. The motherboard ROM and IBMBIO.COM or IO.SYS files
  55. contain the basic drivers for allowing DOS to talk to the console, disk drives,
  56. serial and parallel ports, clock, and other resources.
  57.  
  58.  DOS has five builtin drivers, STDIN, STDOUT, STERR, STDPRN, or STDAUX. An
  59. "installable" driver may be loaded in the CONFIG.SYS file, and either replace
  60. one of the builtin drivers or define a new resource, such as a mouse or
  61. expanded memory driver.
  62.  
  63.  The device driver is a COM (memory image) file that contains all of the code
  64. needed to control an add-in device. An EXE file should not be used since the
  65. EXE loader in some DOS 2.x versions is part of COMMAND.COM, which is not
  66. present when the device driver is being loaded by IBMBIO.COM or IO.SYS. EXE
  67. format drivers could be used in DOS 3.x+, but there is generally no reason to
  68. do so. The COM file must not load at the usual ORG 100h. Since the driver does
  69. not use the Program Segment Prefix, it is simply loaded without offset,
  70. therefore the driver file must have an origin of 0. Most references advise
  71. "ORG 0 or no ORG statement", however with the advent of many new assemblers on
  72. the market, some of which default to .COM files, specifically stating "ORG 0"
  73. may eliminate problems. Driver files should not have a declared stack segment.
  74.  
  75.  DOS can install the device driver anywhere in memory, so care must be taken
  76. in any FAR memory references. You should not expect that your driver will be
  77. loaded in the same place every time.
  78.  
  79.  
  80.  
  81.  
  82. TYPES OF DEVICES├──────────────────────────────────────────────────────────────
  83.  
  84.  There are two types of devices: Character devices and Block devices. Their
  85. attributes are as follows:
  86.  
  87.  Character devices are designed to do serial I/O in a byte-by-byte manner.
  88. These devices have names like CON, AUX, or PRN, and you can open channels
  89. (handles or FCBs) to do I/O much like a disk file. I/O may be in either cooked
  90. or raw mode. (see Chapter 7 for discussion of cooked and raw modes). Because
  91. character devices have only one name, they can only support one device.
  92.  
  93.  Block devices are normally implemented as disk drives. They can do random I/O
  94. in pieces called blocks, which are usually the physical sector size of the disk.
  95. These devices are not named as character devices are, and cannot be opened
  96. directly. Instead they are accessed by using drive letters such as A, B, C,
  97. etc. Block devices can have units within them. In this way, a single block
  98. driver can be responsible for one or more disk drives. For example, the first
  99. block device driver can be responsible for drives A, B, C, and D. This means it
  100. has four units defined and therefore takes up four drive letters. The position
  101. of the driver in the chain of all drives determines the way in which the drive
  102. letters correspond, i.e, if a second block device driver defines three units,
  103. then those units are E, F, and G.
  104.  
  105.  DOS 1.x allows 16 block devices. DOS 2.x allows 63, and DOS 3.x allows 26. It
  106. is recommended that drivers limit themselves to 26 devices for compatibility
  107. with DOS 3.x and 4.x. When DOS 2.x passes the Z: drivespec, the drivespecs get
  108. a little wierd, such as ^, [, or #. DOS 3.x+ will return an error message.
  109.  
  110.  
  111.  
  112.  
  113. CREATING A DEVICE DRIVER├──────────────────────────────────────────────────────
  114.  
  115.  To create a device driver that DOS can install, you must do the following:
  116.  
  117. 1) Create a memory image (COM) file with a device header at the start of the
  118.    file.
  119. 2) Originate the code (including the device header) at 0, instead of 100h.
  120. 3) Set the next device header field. Refer to "Pointer to Next Device Header
  121.    Attribute Field" for more information.
  122. 4) Set the attribute field of the device header. Refer to "Attribute Field" for
  123.    more information.
  124. 5) Set the entry points for the interrupt and strategy routines.
  125. 6) Fill in the name/unit field with the name of the character device or the
  126.    unit number of the block device.
  127.  
  128.  DOS always processes installable character device drivers before handling the
  129. default devices. So to install a new CON device, simply name the device CON.
  130. Be sure to set the standard input device and standard output device bits in
  131. the attribute field of a new CON device. The scan of the device list stops on
  132. the first match so the installable device driver takes precedence. For
  133. instance, installing ANSI.SYS replaces the builtin CON driver.
  134.  
  135.  DOS doesn't care about the position of installed character devices versus
  136. block devices.
  137.  
  138.  
  139.  
  140.  
  141. STRUCTURE OF A DEVICE DRIVER├──────────────────────────────────────────────────
  142.  
  143.  A device driver consists of three major parts:
  144.         a device header
  145.         a strategy routine
  146.         an interrupt routine
  147.  
  148.  
  149. DEVICE HEADER
  150.  
  151.  The driver has a special header to identify it as a device and to define the
  152. strategy and interrupt entry points and its various attributes. This header is
  153. located at the beginning of the file. It contains a pointer to the next driver
  154. in the chain, the attributes of the device, offsets into the strategy and
  155. interrupt routines, and the device ID.
  156.  
  157.  This is the format of the device header:
  158.  
  159. ┌──────────────────────────────────────────────────────────────────────────────┐
  160. │                         D E V I C E    H E A D E R                           │
  161. ├───────┬────────┬─────────────────────────────────────────────────────────────┤
  162. │Offset │ Length │                       Description                           │
  163. ├───────┼────────┼─────────────────────────────────────────────────────────────┤
  164. │  00h  │  word  │  Pointer to next device header field, offset value          │
  165. ├───────┼────────┼─────────────────────────────────────────────────────────────┤
  166. │  02h  │  word  │  Pointer to next device header field, segment value         │
  167. ├───────┼────────┼─────────────────────────────────────────────────────────────┤
  168. │  04h  │  word  │  Attribute                                                  │
  169. ├───────┼────────┼─────────────────────────────────────────────────────────────┤
  170. │  06h  │  word  │  Pointer to device strategy routine (offset only)           │
  171. ├───────┼────────┼─────────────────────────────────────────────────────────────┤
  172. │  08h  │  word  │  Pointer to device interrupt routine (offset only)          │
  173. ├───────┼────────┼─────────────────────────────────────────────────────────────┤
  174. │  0Ah  │8 bytes │  Name/Unit field                                            │
  175. └───────┴────────┴─────────────────────────────────────────────────────────────┘
  176.  
  177.  
  178. POINTER TO NEXT DEVICE HEADER FIELD
  179.  
  180.  The device header field is a pointer to the device header of the next device
  181. driver. It is a doubleword field that is set by DOS at the time the device
  182. driver is loaded. The first word is the offset and the second word is the
  183. segment.
  184.  
  185.  If you are loading only one device driver, set the device header field to -1
  186. before loading the device. If you are loading more than one device driver, set
  187. the first word of the device driver header to the offset of the next device
  188. driver's header. Set the device driver header field of the last device driver
  189. to -1.
  190.  
  191.  
  192. ATTRIBUTE FIELD
  193.  
  194.  The attribute field is a word field used to identify the type of device this
  195. driver is responsible for. This field distinguishes between block and
  196. character devices and determines is selected devices are given special
  197. treatment. The attributes are:
  198.  
  199. ┌──────────────────────────────────────────────────────────────────────────────┐
  200. │                        A T T R I B U T E   F I E L D                         │
  201. ├──────────┬───────┬───────────────────────────────────────────────────────────┤
  202. │   word   │ attr. │                                                           │
  203. ├──────────┼───────┤                     description                           │
  204. │   bits   │  set  │                                                           │
  205. ├──────────┼───────┼───────────────────────────────────────────────────────────┤
  206. │     0    │   0   │   not current standard input device                       │
  207. │          │   1   │   current standard input device                           │
  208. ├──────────┼───────┼───────────────────────────────────────────────────────────┤
  209. │     1    │   0   │   not current standard output device                      │
  210. │          │   1   │   current standard output device                          │
  211. ├──────────┼───────┼───────────────────────────────────────────────────────────┤
  212. │     2    │   0   │   not current NUL device                                  │
  213. │          │   1   │   current NUL device                                      │
  214. ├──────────┼───────┼───────────────────────────────────────────────────────────┤
  215. │     3    │   0   │   not current CLOCK device                                │
  216. │          │   1   │   current CLOCK device                                    │
  217. ├──────────┼───────┼───────────────────────────────────────────────────────────┤
  218. │     4    │   0   │   standard CON I/O routines should be used                │
  219. │          │   1   │   fast screen I/O (int 29h) should be used                │
  220. ├──────────┼───────┴───────────────────────────────────────────────────────────┤
  221. │  5 - 10  │         "reserved for DOS" - unknown - should be set to 0         │
  222. ├──────────┼───────┬───────────────────────────────────────────────────────────┤
  223. │    11    │   0   │   doesn't support removeable media  (default for DOS 2.x) │
  224. │          │   1   │   supports removeable media         (DOS 3.0+ only)       │
  225. ├──────────┼───────┴───────────────────────────────────────────────────────────┤
  226. │    12    │         "reserved for DOS" - unknown - should be set to 0         │
  227. ├──────────┼───────┬───────────────────────────────────────────────────────────┤
  228. │    13    │   0   │   IBM format       (block devices)                        │
  229. │          │   1   │   non-IBM format   (block devices)                        │
  230. │          │   1   │   output till busy (character devices)                    │
  231. ├──────────┼───────┼───────────────────────────────────────────────────────────┤
  232. │    14    │   0   │   doesn't support IOCTL                                   │
  233. │          │   1   │   supports IOCTL                                          │
  234. ├──────────┼───────┼───────────────────────────────────────────────────────────┤
  235. │    15    │   0   │   block device                                            │
  236. │          │   1   │   character device                                        │
  237. └──────────┴───────┴───────────────────────────────────────────────────────────┘
  238.  
  239. note 1) If a bit in the attribute word is defined only for one type of device,
  240.         a driver for the other type of device must set that bit to 0.
  241.      2) For DOS 2.0 bits 4-12 must be off.
  242.  
  243.  
  244. BIT 1   is the standard input and output bit. It is used for character devices
  245.         only. Use this bit to tell DOS if your character device driver is the
  246.         new standard input device or standard output device.
  247.  
  248. BIT 2   is the NUL attribute bit. It is used for character devices only. Use it
  249.         to tell DOS if your character device driver is a NUL device. Although
  250.         there is a NUL device attribute bit, you cannot reassign the NUL
  251.         device or replace it with your own routine. This attribute exists for
  252.         DOS so that DOS can tell if the NUL device is being used.
  253.  
  254. BIT 3   is the clock device bit. It is used for character devices only. Default
  255.         is 0. You can use it to tell DOS if your character device driver is the
  256.         new CLOCK device.
  257.  
  258. BIT 4   is the "fast video output" bit. The default is 0, which uses the BIOS
  259.         for writing to the screen. When set, this bit uses int 29h for much
  260.         faster screen updates.
  261.  
  262. BITS 5-10  reserved for DOS, unknown. Should be set to 0.
  263.  
  264. BIT 11  is the open/close removeable media bit. Use it to tell DOS if the
  265.         device driver can handle removeable media. This bit is valid for DOS
  266.         3.0+ only. This bit was reserved in DOS 2.x. Since DOS 2.x does not
  267.         look at this bit, its use is backward compatible.
  268.  
  269. BIT 12  reserved for DOS, unknown. Should be set to 0.
  270.  
  271. BIT 13  is the non-IBM format bit. When used for block devices it affects the
  272.         operation of the BUILD BPB (BIOS parameter block) device call. For
  273.         character devices it indicates that the devices implements the OUTPUT
  274.         UNTIL BUSY device call.
  275.  
  276. BIT 14  is the IOCTL bit. It is used for both character and block devices. Use
  277.         it to tell DOS whether the device driver can handle control strings
  278.         through the IOCTL function call 44h.
  279.          If a device driver cannot process control strings, it should set bit
  280.         14 to 0. This way DOS can return an error if an attempt is made through
  281.         the IOCTL function call to send or receive control strings to the
  282.         device. If a device can process control strings, it should set bit 14
  283.         to 1. This way, DOS makes calls to the IOCTL input and output device
  284.         function to send and receive IOCTL strings.
  285.          The IOCTL functions allow data to be sent to and from the device
  286.         without actually doing a normal read or write. In this way, the device
  287.         driver can use the data for its own use, (for example, setting a baud
  288.         rate or stop bits, changing form lengths, etc.) It is up to the device
  289.         to interpret the information that is passed to it, but the information
  290.         must not be treated as a normal I/O request.
  291.  
  292. BIT 15  is the device type bit. Use it to tell the system the that driver is a
  293.         block or character device.
  294.  
  295.  
  296. POINTER TO STRATEGY ROUTINE
  297.  
  298.  This field contains a pointer to "device strategy" function in the driver.
  299. This function is called whenever a request is made to the driver, and must
  300. store the location of the request header from DOS. This pointer is a word
  301. value, and so must be in the same segment as the device header.
  302.  
  303.  
  304. POINTER TO INTERRUPT ROUTINE
  305.  
  306.  This field contains a pointer to the function which activates driver routines
  307. to perform the command in the current request header. This is called by DOS
  308. after the call to the strategy function, and should reset to the request header
  309. address stored by "strategy", to allow for the possibility of interrupts
  310. between the two calls. This pointer is a word value, and so must be in the same
  311. segment as the device header.
  312.  
  313.  
  314. NAME/UNIT FIELD
  315.  
  316.  This is an 8-byte field that contains the name of a character device or the
  317. number of units in a block device. For the character names, the name is
  318. left-justified and the space is filled to 8 bytes. For block devices, the
  319. number of units can be placed in the first byte. This is optional because DOS
  320. fills in this location with the value returned by the driver's INIT code. The
  321. other 7 bytes of the block device ID are reserved and should not be used.
  322.  
  323.  
  324.  
  325. INSTALLING DEVICE DRIVERS├─────────────────────────────────────────────────────
  326.  
  327.  DOS installs new device drivers dynamically at boot time by reading and
  328. processing the DEVICE command in the CONFIG.SYS file. For example, if you have
  329. written a device driver called RAMDISK, to install it put this command in the
  330. CONFIG.SYS file:
  331.                    DEVICE=[drive][path] RAMDISK [parameters]
  332.  
  333.  DOS makes a FAR call to the device driver at its strategy entry point first,
  334. using the request header to pass information describing what DOS wants the
  335. device driver to do.
  336.  
  337.  This strategy routine does not perform the request but rather queues the
  338. request or saves a pointer to the request header. The second entry point is
  339. the interrupt routine and is called by DOS immediately after the strategy
  340. routine returns. The interrupt routine is called with no parameters. Its
  341. function is to perform the operation based on the queued request and set up
  342. any return infromation.
  343.  
  344.  DOS passes the pointer to the request header in ES:BX. This structure consists
  345. of a fixed length header (Request Header) followed by data pertinent to the
  346. operation to be performed.
  347.  
  348. NOTE: It is the responsibility of the device driver to preserve the machine
  349.       state. For example, save all registers on entry and restore them on exit.
  350.  
  351.  The stack used by DOS has enough room on it to save all the registers. If more
  352. stack space is needed, it is the device driver's responsibility to allocate and
  353. maintain another stack.
  354.  
  355.  All calls to execute device drivers are FAR calls. FAR returns should be
  356. executed to return to DOS.
  357.  
  358.  
  359.  
  360. INSTALLING CHARACTER DEVICES
  361.  
  362.   One of the functions defined for each device is INIT. This routine is called
  363. only once when the device is installed and never again. The INIT routine returns
  364. the following:
  365.  
  366. A) A location to the first free byte of memory after the device driver, like a
  367.    TSR that is stored in the terminating address field. This way, the
  368.    initialization code can be used once and then thrown away to save space.
  369. B) After setting the address field, a character device driver can set the status
  370.    word and return.
  371.  
  372.  
  373.  
  374. INSTALLING BLOCK DEVICES
  375.  
  376.  Block devices are installed in the same way as character devices. The
  377. difference is that block devices return additional information. Block devices
  378. must also return:
  379.  
  380. A) The number of units in the block device. This number determines the logical
  381.    names the devices will have. For example, if the current logical device
  382.    letter is F at the time of the install call, and the block device driver INIT
  383.    routine returns three logical units, the letters G, H, and I are assigned to
  384.    the units. The mapping is determined by the position of the driver in the
  385.    device list and the number of units in the device. The number of units
  386.    returned by INIT overrides the value in the name/unit field of the device
  387.    header.
  388.  
  389. B) A pointer to a BPB (BIOS Parameter Block) pointer array. This is a pointer
  390.    to an array of "N" word pointers there "N" is the number of units defined.
  391.    These word pointers point to BPBs. This way, if all of the units are the
  392.    same, the entire array can point to the same BPB to save space.
  393.     The BPB contains information pertinent to the devices such as the sector
  394.    size, number of sectors per allocation unit, and so forth. The sector size of
  395.    the BPB cannot be greater than the maximum allotted size set at DOS
  396.    initialization time. This array must be protected below the free pointer set
  397.     by the return.
  398.  
  399. C) The media descriptor byte. This byte is passed to devices so that they know
  400.    what parameters DOS is currently using for a particular drive unit.
  401.  
  402.  Block devices can take several approaches. They can be "dumb" or "smart". A
  403. dumb device would define a unit (and therefore a BPB) for each possible media
  404. drive combination. Unit 0=drive 0;single side, unit 1=drive 0;double side, etc.
  405. For this approach, the media descriptor bytes would mean nothing. A smart
  406. device would allow multiple media per unit. In this case, the BPB table
  407. returned at INIT must define space large enough to acommodate the largest
  408. possible medias supported (sector size in BPB must be as large as maximum
  409. sector size DOS is currently using). Smart drivers will use the media
  410. descriptor byte to pass information about what media is currently in a unit.
  411.  
  412.  
  413.  
  414. REQUEST HEADER├────────────────────────────────────────────────────────────────
  415.  
  416.  The request header passes the information describing what DOS wants the
  417. device driver to do.
  418.  When a valid device driver command code or function is called by your
  419. application program, DOS develops a data structure called the "Request Header"
  420. in ES:BX and passes it to the strategy entry point. This structure consists of
  421. a 13-byte defined header which may be followed by other data bytes depending on
  422. the function requested.
  423.  It is the device driver's responsibility to preserve the machine state, for
  424. example, saving all registers including flags on entry and restoring them on
  425. exit. There is enough room on the stack when strategy or interrupt is called
  426. to do about 20 pushes. If more stack is needed, the driver should set aside
  427. its own stack space.
  428.  The fixed ("static") part of the request header is as follows:
  429.  
  430. ┌────────────────────────────────────────────────────────────────────────────┐
  431. │                        R E Q U E S T    H E A D E R                        │
  432. ├───────┬───────┬────────────────────────────────────────────────────────────┤
  433. │Offset │Length │                      F i e l d                             │
  434. ├───────┼───────┼────────────────────────────────────────────────────────────┤
  435. │  00h  │  byte │ Length in bytes of the request header plus any data at end │
  436. ├───────┼───────┼────────────────────────────────────────────────────────────┤
  437. │  01h  │  byte │ Unit code. Determines subunit to use in block devices      │
  438. │       │       │ (minor device)  Has no meaning for character devices       │
  439. ├───────┼───────┼────────────────────────────────────────────────────────────┤
  440. │  02h  │  byte │ Command code                                               │
  441. ├───────┼───────┼────────────────────────────────────────────────────────────┤
  442. │  03h  │  word │ Status                                                     │
  443. ├───────┼───────┼────────────────────────────────────────────────────────────┤
  444. │  05h  │8 bytes│ Reserved for DOS                                           │
  445. ├───────┼───────┼────────────────────────────────────────────────────────────┤
  446. │  0Ch  │varies │ Data appropriate for the operation                         │
  447. └───────┴───────┴────────────────────────────────────────────────────────────┘
  448.  
  449. REQUEST HEADER LENGTH FIELD
  450.  
  451.  The length in bytes of the total request header (0-255) plus any data at the
  452. end of the header.
  453.  
  454.  
  455. UNIT CODE FIELD
  456.  
  457.  The unit code field identifies which unit in a block device driver the request
  458. is for. For example, if a block device driver has three units defined, then the
  459. possible values of the unit code field would be 0, 1, and 2. This field is not
  460. valid for character devices.
  461.  
  462.  
  463. COMMAND CODE FIELD
  464.  
  465.  The command code invokes a specific device driver function. Functions 0
  466. through 12 are supported in all device drivers. Functions 13-15 are available
  467. only in DOS 3.0 or higher. Some functions are relevant for either character or
  468. block devices but not both; nonetheless all functions must have an executable
  469. routine present even if it does nothing but set the done flag in the return
  470. status word in the request header.
  471.  
  472.  The command code field in the request header can have the following values:
  473. ┌──────┬──────────────────┬────────────────────────────────────────────────────┐
  474. │ code │       name       │                     function                       │
  475. ├──────┼──────────────────┼────────────────────────────────────────────────────┤
  476. │   0  │ INIT             │ initialize driver for later use (used once only)   │
  477. │   1  │ MEDIA CHECK      │ block devices only, NOP for character devices      │
  478. │   2  │ BUILD BPB        │ block devices only, NOP for character devices      │
  479. │   3  │ IOCTL input      │ called only if device has IOCTL bit set            │
  480. │   4  │ INPUT            │ read data                                          │
  481. │   5  │ NONDESTRUCTIVE INPUT NO WAIT  character devices only                  │
  482. │   6  │ INPUT STATUS     │ character devices only                             │
  483. │   7  │ INPUT FLUSH      │ character devices only                             │
  484. │   8  │ OUTPUT           │ write data                                         │
  485. │   9  │ OUTPUT           │ write data with verify                             │
  486. │  10  │ OUTPUT STATUS    │ character devices only                             │
  487. │  11  │ OUTPUT FLUSH     │ character devices only                             │
  488. │  12  │ IOCTL OUTPUT     │ called only if device has IOCTL bit is set         │
  489. │  13  │ DEVICE OPEN      │ called only if OPEN/CLOSE/RM bit is set            │
  490. │  14  │ DEVICE CLOSE     │ called only if OPEN/CLOSE/RM bit is set            │
  491. │  15  │ REMOVEABLE MEDIA │ only if OPEN/CLOSE/RM bit set & device is block    │
  492. │  16  │ OUTPUT UNTIL BUSY│ only called if bit 13 is set & device is character │
  493. └──────┴──────────────────┴────────────────────────────────────────────────────┘
  494.  
  495.  The individual command codes are described later in this chapter.
  496.  
  497.  
  498.  
  499. STATUS FIELD
  500.  
  501.  The status word field is zero on entry and is set by the driver interrupt
  502. routine on return.
  503.  
  504. The status field in the request header contains:
  505.  
  506. ┌─────────────────────────────────────────────────────────────────────────────┐
  507. │            D E V I C E    D R I V E R    S T A T U S    F I E L D           │
  508. ├───────┬───┬─────────────────────────────────────────────────────────────────┤
  509. │ size  │bit│                        definition                               │
  510. ├───────┼───┼─────────────────────────────────────────────────────────────────┤
  511. │ byte  │ 0 │                                                                 │
  512. │       │ 1 │                                                                 │
  513. │       │ 2 │                                                                 │
  514. │       │ 3 │  Error message return code                                      │
  515. │       │ 4 │  (with bit 15=1)                                                │
  516. │       │ 5 │                                                                 │
  517. │       │ 6 │                                                                 │
  518. │       │ 7 │                                                                 │
  519. ├───────┼───┼─────────────────────────────────────────────────────────────────┤
  520. │ byte  │ 8 │  DONE                                                           │
  521. │       ├───┼─────────────────────────────────────────────────────────────────┤
  522. │       │ 9 │  BUSY                                                           │
  523. │       ├───┼─────────────────────────────────────────────────────────────────┤
  524. │       │ A │  Reserved by DOS, unknown                                       │
  525. │       │ B │                                                                 │
  526. │       │ C │                                                                 │
  527. │       │ D │                                                                 │
  528. │       │ E │                                                                 │
  529. │       ├───┼─────────────────────────────────────────────────────────────────┤
  530. │       │ F │  Error                                                          │
  531. └───────┴───┴─────────────────────────────────────────────────────────────────┘
  532.  
  533.  
  534.  The low 8 bits of the status word define an error message if bit 15 is set.
  535. These errors are:
  536.  
  537.         00h  write protect violation   01h  unknown unit
  538.         02h  device not ready          03h  unknown command
  539.         04h  CRC error                 05h  bad drive request structure length
  540.         06h  seek error                07h  unknown media
  541.         08h  sector not found          09h  printer out of paper
  542.         0Ah  write fault               0Bh  read fault
  543.         0Ch  general failure           0Dh  reserved
  544.         0Eh  reserved                  0Fh  invalid disk change
  545.  
  546. BIT 8   is the done bit. If it is set, it means the operation is complete. The
  547.         driver sets the bit to 1 when it exits.
  548.  
  549. BIT 9   is the busy bit. It is only set by status calls and the removable media
  550.         call.
  551.  
  552. BITS 10-14 are reserved.
  553.  
  554. BIT 15  is the error bit. If this bit is set, the low 8 bits of the status word
  555.         (7-0) indicate the error code.
  556.  
  557.  
  558. RESERVED FOR DOS
  559.  Official sources label this area as "reserved for DOS". Another source
  560. indicates that this consists of two double-word (4-byte) pointers to be used
  561. to maintain a linked list of request headers for this device and a list of all
  562. current device requests being processed by DOS. This was apparently to be used
  563. for the undelivered multitasking version of DOS.
  564.  
  565.  
  566.  
  567. DEVICE DRIVER FUNCTIONS├───────────────────────────────────────────────────────
  568.  
  569.  All strategy routines are called with ES:BX pointing to the request header.
  570. The interrupt routines get the pointers to the request header from the queue
  571. the strategy routines stores them in. The command code in the request header
  572. tells the driver which function to perform.
  573.  
  574. NOTE: All DWORD pointers are stored offset first, then segment.
  575.  
  576.                          ############################
  577.  
  578. INIT
  579. Command code = 0        (all devices)
  580.         Performs all initialization required at DOS boot time to install the
  581.         driver and set local driver variables. This function is called only
  582.         once, when the driver is loaded.
  583.  
  584.         ES:BX   pointer to 26-byte request header and data structure
  585.  Format of structure:
  586.        offset     length          field
  587.          00h    13 bytes   request header
  588.          0Dh       byte    number of units (not set by character devices)
  589.          11h       dword   ending address of the driver's resident code
  590.          15h       dword   pointer to BPB array (not set by character devices)
  591.                            /pointer to remainder of arguments
  592.          19h       byte    drive number (DOS 3.0+ only)
  593.  
  594.  
  595.  When INIT is called, the driver must do the following:
  596.  
  597.         A) set the number of units (block devices only)
  598.         B) set up the pointer to the BPB array (block devices only)
  599.         C) perform any initialization code (to modems, printers, etc)
  600.         D) set the ending address of the resident program code
  601.         E) set the status word in the request header
  602.  
  603.  To obtain information obtained from CONFIG.SYS to a device driver at INIT
  604. time, the BPB pointer field points to a buffer containing the information
  605. passed from CONFIG.SYS following the =. The buffer that DOS passes to the
  606. driver at INIT after the file specification contains an ASCII string for the
  607. file OPEN. The ASCII string (ending in 0h) is terminated by a carriage return
  608. (0Dh) and linefeed (0Ah). If there is no parameter information after the file
  609. specification, the file specification is immediately followed by a linefeed
  610. (0Ah).
  611.  
  612.  NOTE: This information is read-only and only system calls 01h-0Ch and 30h can
  613.        be issued by the INIT code of the driver.
  614.  
  615.  The last byte parameter contains the drive letter for the first unit of a
  616. block driver. For example, 0=A, 1=B etc.
  617.  
  618.  If an INIT routine determines that it cannot set up the device and wants to
  619. abort without using any memory, follow this procedure:
  620.  
  621.         A) set the number of units to 0
  622.         B) set the ending offset address at 0
  623.         C) set the ending offsret segment address to the code segment (CS)
  624.  
  625. NOTE: If there are multiple device drivers in a single memory image file, the
  626.       ending address returned by the last INIT called is the one DOS uses. It is
  627.       recommended that all device drivers in a single memory image file return
  628.       the same ending address.
  629.  
  630.                          ############################
  631.  
  632. MEDIA CHECK
  633. command code = 1        (block devices only)
  634.         Checks to see if disk had been changed since last access.
  635.  
  636.         ES:BX   pointer to 19-byte request header and data structure
  637.  Format of structure:
  638.         offset  length          field
  639.         00h     13 bytes   request header
  640.         0Dh        byte    media descriptor from BPB
  641.         0Eh        byte    returned
  642.         0Fh       dword    returns a pointer to the previous volume ID (if bit
  643.                            11=1 and disk change is returned) (DOS 3.0+)
  644.  
  645.  When the command code field is 1, DOS calls MEDIA CHECK for a drive unit and
  646. passes its current media descriptor byte. See "Media Descriptor Byte" later in
  647. this chapter for more information about the byte. MEDIA CHECK returns one of
  648. the following:
  649.  
  650.         A) media not changed             C) not sure
  651.         B) media changed                 D) error code
  652.  
  653. The driver must perform the following:
  654.         A) set the status word in the request header
  655.         B) set the return byte
  656.                 00h   don't know if media has been changed
  657.                 01h   media has not been changed
  658.                 -1    media has been changed
  659.  
  660.  DOS 3.0+: If the driver has set the removable media bit 11 of the device header
  661. attribute word to 1 and the driver returns -1 (media changed), the driver must
  662. set the DWORD pointer to the previous volume identification field. If DOS
  663. determines that the media changed is an error, DOS generates an error 0Fh
  664. (invalid disk change) on behalf of the device. If the driver does not implement
  665. volume identification support, but has bit 11 set to 1, the driver should set a
  666. pointer to the string "NO NAME",0.
  667.  
  668.  
  669. MEDIA DESCRIPTOR
  670.  Currently the media descriptor byte has been defined for a few media types.
  671. This byte should be identical to the media byte if the device has the non-IBM
  672. format bit off. These predetermined values are:
  673.  
  674. media descriptor byte =>    1  1  1  1  1  0  0  0
  675.  (numeric order)            7  6  5  4  3  2  1  0
  676.  
  677.        BIT                MEANING
  678.  
  679.         0       0       not double sided
  680.                 1       double sided
  681.         1       0       not 8 sector
  682.                 1       8 sector
  683.         2       0       nonremoveable
  684.                 1       removeable
  685.        3-7      must be set to 1
  686.  
  687.                          ############################
  688.  
  689. BUILD BPB (BIOS Parameter Block)
  690. command code = 2        (block devices only)
  691.  
  692.         ES:BX   pointer to 22-byte request header and data structure
  693.  Format of structure:
  694.         offset   length          field
  695.         00h     13 bytes   request header
  696.         0Dh        byte    media descriptor from DOS
  697.         0Eh       dword    transfer address (buffer address)
  698.         12h       dword    pointer to BPB table
  699.  
  700. DOS calls BUILD BPB under the following two conditions:
  701.  
  702. A) If "media changed" is returned.
  703. B) If "not sure" is returned. If so, there are no used buffers. Used buffers
  704.    are buffers with changed data that have not yet been written to the disk.
  705.  
  706. The driver must do the following:
  707.  
  708. A) set the pointer to the BPB.
  709. B) set the status word in the request header.
  710.  
  711.  The driver must determine the correct media type currently in the unit to
  712. return the pointer to the BPB table. The way the buffer is used (pointer
  713. passed by DOS) is determined by the non-IBM format bit in the attribute field
  714. of the device header. If bit 13=0 (device is IBM compatible), the buffer
  715. contains the first sector of the FAT (most importantly the FAT ID byte). The
  716. driver must not alter this buffer in this case. If bit 13=1 the buffer is a
  717. one sector scratch area which can be used for anything.
  718.  
  719.  For drivers that support volume identification and disk change, the call
  720. should cause a new volume identification to be read off the disk. This call
  721. indicates that the disk has been legally changed.
  722.  
  723.  If the device is IBM compatible, it must be true that the first sector of the
  724. first FAT is located at the same sector for all possible media. This is
  725. because the FAT sector is read before the media is actually determined.
  726.  
  727.  The information relating to the BPB for a particular media is kept in the boot
  728. sector for the media. In particular, the format of the boot sector is:
  729.  
  730. ┌──────────────────────────────────────────────────────────────────────────────┐
  731. │ For DOS 2.x, 3 byte near jump (0E9h) For DOS 3.x+, 2 byte near jump (0EBh)   │
  732. │ followed by a NOP (90h)                                                      │
  733. ├──────────┬───────────────────────────────────────────────────────────────────┤
  734. │ 8 bytes  │  OEM name and version                                             │
  735. ├──────────┼─────┬─────────────────────────────────────────────────────────────┤
  736. │   BYTE   │     │  sectors per allocation unit (must be a power of 2)         │
  737. ├──────────┤     ├─────────────────────────────────────────────────────────────┤
  738. │   WORD   │  B  │  reserved sectors (strarting at logical sector 0)           │
  739. ├──────────┤     ├─────────────────────────────────────────────────────────────┤
  740. │   BYTE   │     │  number of FATs                                             │
  741. ├──────────┤     ├─────────────────────────────────────────────────────────────┤
  742. │   WORD   │  P  │  max number of root directory entries                       │
  743. ├──────────┤     ├─────────────────────────────────────────────────────────────┤
  744. │   WORD   │     │  number of sectors in logical image (total number of        │
  745. │          │     │  sectors in media, including boot sector directories, etc.) │
  746. ├──────────┤  B  ├─────────────────────────────────────────────────────────────┤
  747. │   BYTE   │     │  media descriptor                                           │
  748. ├──────────┤     ├─────────────────────────────────────────────────────────────┤
  749. │   WORD   │     │  number of sectors occupied by a single FAT                 │
  750. ├──────────┼─────┴─────────────────────────────────────────────────────────────┤
  751. │   WORD   │  sectors per track                                                │
  752. ├──────────┼───────────────────────────────────────────────────────────────────┤
  753. │   WORD   │  number of heads                                                  │
  754. ├──────────┼───────────────────────────────────────────────────────────────────┤
  755. │   WORD   │  number of hidden sectors                                         │
  756. └──────────┴───────────────────────────────────────────────────────────────────┘
  757.  
  758.  The three words at the end return information about the media. The number of
  759. heads is useful for supporting different multihead drives that have the same
  760. storage capacity but a different number of surfaces. The number of hidden
  761. sectors is useful for drive partitioning schemes.
  762.  
  763.                          ############################
  764.  
  765. INPUT / OUTPUT  (IOCTL)
  766. command code = 3   IOCTL Read
  767.                4   Read              (block or character devices)
  768.                8   Write             (block or character devices)
  769.                9   Write With Verify
  770.               12   IOCTL Write
  771.               16   Output Until Busy (character devices only)
  772.  
  773.         ES:BX   pointer to 24-byte request header and data structure
  774.  
  775.   Format of structure:
  776.         offset    length          field
  777.         00h     13 bytes     request header
  778.         0Dh        byte      media descriptor byte from BPB
  779.         0Eh       dword      transfer address (buffer address)
  780.         12h        word      byte/sector count
  781.         14h        word      starting sector number (block devices)
  782.                              [no meaning on character devices]
  783.         16h       dword      (DOS 3.0+) pointer to the volume ID if error code
  784.                              0Fh is returned
  785.  
  786. The driver must perform the following:
  787.         A) set the status word in the request header
  788.         B) perform the requested function
  789.         C) set the actual number of sectors or bytes tranferred
  790.  
  791.  No error checking is performed on an IOCTL I/O call. However, the driver must
  792. set the return sector or byte count to the actual number of bytes transferred.
  793.  
  794.  Under certain circumstances a block device driver may be asked to do a write
  795. operation of 64k bytes that seems to be a "wrap around" of the transfer address
  796. in the BIOS I/O packet. This arises due to an optimization added to write code
  797. in DOS. It will only happen in writes that are within a sector size of 64k on
  798. files that are being extended past the current end of file. It is allowable for
  799. the device driver to ignore the balance of the write that wraps around, if it
  800. so chooses. For example, a write of 10000h bytes worth of sectors with a
  801. transfer address of XXX:1 ignores the last two bytes. A user program can never
  802. request an I/O of more than 0FFFFh bytes and cannot wrap around (even to 0) in
  803. the transfer segment, so in that case the last two bytes can be ignored.
  804.  
  805.  A program that uses DOS function calls can never request an input or output
  806. function of more than 0FFFFh bytes, therefore, a wrap around in the transfer
  807. (buffer) segment can never occur. It is for this reason you can ignore bytes
  808. that would have wrapped around in the tranfer segment.
  809.  
  810.  If the driver returns an error code of 0Fh (invalid disk change) it must put
  811. a DWORD pointer to an ASCIIZ string which is the correct volume ID to ask the
  812. user to reinsert the disk.
  813.  
  814. DOS 3.0+:
  815.  The reference count of open files on the field (maintained by the OPEN and
  816. CLOSE calls) allows the driver to determine when to return error 0Fh. If there
  817. are no open files (reference count=0) and the disk has been changed, the I/O
  818. is all right, and error 0Fh is not returned. If there are open files
  819. (reference count > 0) and the disk has been changed, an error 0Fh condition
  820. may exist.
  821.  
  822.                          ############################
  823.  
  824. NONDESTRUCTIVE INPUT NO WAIT
  825. command code = 5        (character devices only)
  826.         Reads a character from input stream but does not remove it from the
  827.         buffer
  828.  
  829.         ES:BX   pointer to 14-byte request header and data structure
  830.  Format of structure:
  831.         offset    length          field
  832.         00h     13 bytes   request header
  833.         0Dh        byte    read from device
  834.  
  835. The driver must do the following:
  836.         A) return a byte from the device
  837.         B) set the status word in the request header.
  838.  
  839.  If the character device returns busy bit=0 (characters in the buffer), then
  840. the next character that would be read is returned. This character is not removed
  841. form the buffer (hence the term nondestructive input). This call allows DOS to
  842. look ahead one character.
  843.  
  844.                          ############################
  845.  
  846. STATUS
  847. command codes =  6   Input Status      (character devices only)
  848.                 10   Output Status     (character devices only)
  849.         Check for characters waiting in input buffer
  850.  
  851.         ES:BX   pointer to 13-byte request header
  852.  
  853. This driver must perform the following:
  854.         A) perform the requested function
  855.         B) set the busy bit
  856.         C) set the status word in the request header.
  857.  
  858. The busy bit is set as follows:
  859.  
  860.  For input on unbuffered character devices: if the busy bit (bit 9) is 1 on
  861. return, a write request would wait for completion of a current request. If the
  862. busy bit is 0, there is no current request. Therefore, a write request would
  863. start immediately.
  864.  
  865.  For input on buffered character devices: if the busy bit is 1 on return, a
  866. read request does to the physical device. If the busy bit is 0, there are
  867. characters in the device buffer and a read returns quickly. It also indicates
  868. that a user has typed something. DOS assumes all character devices have a type-
  869. ahead input buffer. Devices that do not have this buffer should always return
  870. busy=0 so that DOS does not hang waiting for information to be put in a buffer
  871. that does not exist.
  872.  
  873.                          ############################
  874.  
  875. FLUSH INPUT BUFFERS
  876. command code = 7        (character devices only)
  877.         Forces all data in buffers to specified device.
  878.  
  879.         ES:BX   pointer to 13-byte request header
  880.  
  881.  This call tells the driver to flush (terminate) all pending requests that it
  882. has knowledge of. Its primary use is to flush the input queue on character
  883. devices.
  884.  
  885.  The driver must set the status word in the request header upon return.
  886.  
  887.                          ############################
  888.  
  889. FLUSH OUTPUT BUFFERS
  890. command code 11         (character devices only)
  891.         Forces all data in buffers to specified device.
  892.  
  893.         ES:BX   pointer to 13-byte request header
  894.  
  895.  
  896.  This call tells the driver to flush all output buffers and discards any
  897. pending requests. Its primary use is to flush the output queue on character
  898. devices.
  899.  
  900.  The driver must set the status word in the request header upon return.
  901.  
  902.                          ############################
  903.  
  904. OPEN or CLOSE  (DOS 3.0+)
  905. command code = 13   Open      (block or character devices)
  906.                14   Close     (block or character devices)
  907.  
  908.         ES:BX   pointer to 13-byte static request header
  909.  
  910.  These calls are designed to give the device information about the current file
  911. activity on the device if bit 11 of the attribute word is set. On block
  912. devices, these calls can be used to manage local buffering. The device can keep
  913. a reference count. Every OPEN causes the device to increment the reference
  914. count. Every CLOSE causes the device to decrement the reference count. When the
  915. reference count is 0, if means there are no open files in the device. Therefore,
  916. the device should flush buffers inside the device it has written to because now
  917. the user can change the media on a removeable media drive. If the media had been
  918. changed, it is advisable to reset the reference count to 0 without flushing the
  919. buffers. This can be thought of as "last close causes flush". These calls are
  920. more useful on character devices. The OPEN call can be used to send a device
  921. initialization string. On a printer, this could cause a string to be sent to set
  922. the font, page size, etc. so that the printer would always be in a known state
  923. in the I/O stream. Similarly, a CLOSE call can be used to send a post string
  924. (like a form feed) at the end of an I/O stream. Using IOCTL to set these pre and
  925. post strings provides a flexible mechanism of serial I/O device stream control.
  926.  
  927.  Since all processes have access to STDIN, STDOUT, STDERR, STDAUX, and STDPRN
  928. (handles 0, 1, 2, 3, and 4) the CON, AUX, and PRN devices are always open.
  929.  
  930.                          ############################
  931.  
  932. REMOVABLE MEDIA  (DOS 3.0+)
  933. command code = 15       (block devices only)
  934.         This call identifies the media type as removable or nonremovable.
  935.  
  936.         ES:BX   pointer to 13-byte static request header
  937.  
  938.  To use this call, set bit 11 (removable media) of the attribute field to 1.
  939. Block devices can only use this call through a subfunction of the IOCTL
  940. function call (int 21h fn44h).
  941.  This call is useful because it allows a utility to know whether it is dealing
  942. with a nonremovable media drive or with a removable media drive. For example,
  943. the FORMAT utility needs to know whether a drive is removable or nonremovable
  944. because it prints different versions of some prompts.
  945.  
  946. note    No error checking is performed. It is assumed that this call always
  947.         succeeds.
  948.  
  949.  
  950. THE CLOCK$ DEVICE├─────────────────────────────────────────────────────────────
  951.  
  952.  To allow a clock board to be integrated into the system for TIME and DATE,
  953. the CLOCK$ device is used. This device defines and performs functions like any
  954. other character device (most functions will be reset done bit, reset error bit,
  955. and return). When a read or write to this device occurs, 6 bytes are
  956. transferred. The first 2 bytes are a word, which is the count of days since
  957. 01-01-80. The third byte is minutes, the fourth is hours, the fifth is
  958. hundredths of a second, and the sixth is seconds.
  959.  
  960.  Reading the CLOCK$ device gets the date and time, writing to it sets the date
  961. and time. CLOCK$ is normally called only when the system is initializing or if
  962. the system time and date are set (DOS 3.3+). DOS carries the system time and
  963. date internally after receiving it from the CLOCK$ driver.
  964.  
  965.  
  966.  
  967.  
  968.